<?php
// $Id: Repository.interface.php 73 2007-02-12 03:45:43Z tswicegood $

/**
 * This file contains {@link Repository} which is part of the PHP Content Repository
 * (phpCR), a derivative of the Java Content Repository JSR-170,  and is 
 * licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */


/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/phpCR.library.php');

phpCR::loadInterface('Credentials');
phpCR::loadInterface('Ticket');


/**
 * The entry point into the content repository.
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface Repository
{
   /**
    * Login and return a new {@link Ticket} for the given credentials and 
    * specified {@link Workspace}.
    * 
    * If login fails, a {@link LoginException} is thrown and no valid ticket 
    * is generated.
    *
    * How the repository treats an attempt to connect with NULL
    * {@link Credentials} and or a NULL $workspaceName 
    * is a matter of implementation. Possibilities include allowing an 
    * anonymous connection in cases of NULL {@link Credentials} 
    * and connecting to a default workspace in cases of a 
    * NULL $workspaceName.  
    * 
    * <b>PHP Note</b>:$credentials must be derived from the {
    * @link Credentials} class.
    *
    * <b>Level 2:</b>
    *
    * Returns a {@link Ticket} object in order to support transactions.
    *
    * @param object
    *   The {@link Credentials} of the user
    * @param string
    *   The name of a workspace.
    * @return object
    *   A valid {@link Ticket} for the user to access the repository.
    * @throws {@link LoginException}
    *   If the login authentication fails.
    * @throws {@link NoSuchWorkspaceException}
    *   If the specified $workspaceName is not recognized.
    */
    public function login(Credentials $credentials, $workspaceName);
}

